The Serena tool prompt lacked practical guidance optimized for AI agent decision-making. Analysis of 20 workflows revealed common patterns and anti-patterns. The file has been restructured from documentation-style to action-oriented agent prompt.

Changes

Redefined purpose and scope

• Changed from vague "advanced static analysis" to precise "LSP MCP server for semantic code analysis"
• Added explicit ✅ use cases: symbol analysis, call graphs, semantic patterns, refactoring opportunities
• Added explicit ❌ anti-patterns: text operations, grep-suitable tasks, config files

Optimized for agentic planning

• Reduced file size by 46% (323 → 173 lines) for faster agent processing
• Restructured as action-oriented decision guide with Quick Decision section at top
• Converted prose to scannable bullet points and numbered action sequences
• Categorized tools by function (Navigation & Analysis, Code Editing, Project Management)
• Replaced lengthy examples with concise step-by-step workflows

Documented production patterns

• Extracted from go-fan (97.6% success), sergo (94.4% success), and 3 other workflows
• Pattern 1: Find all function usages (3-step sequence)
• Pattern 2: Code quality analysis (4-step sequence)
• Pattern 3: Daily code analysis (5-step sequence with caching)

Tool reference

• Navigation: find_symbol, get_symbols_overview, find_referencing_code_snippets
• Editing: replace_symbol_body, insert_at_line, delete_lines
• Analysis: search_for_pattern, activate_project, onboarding

Common pitfalls section

• Using Serena for YAML/JSON/Markdown (use edit instead)
• Forgetting activate_project first
• Not combining with bash for file discovery
• Missing language configuration

Decision tree

Requires code semantics/structure?
├─ NO → bash/edit/view
└─ YES
    ├─ Simple text/grep → bash/grep
    ├─ Config files → edit
    └─ Symbol/structure/patterns → Serena

Removed per feedback

• Language detection section (agents can use standard file indicators)
• Serena memory tools (write_memory, read_memory, list_memories) and related best practices

Result

File optimized from 87 to 173 lines (originally expanded to 323). Agents can now make instant YES/NO decisions using top-of-file criteria, with all essential information in a scannable, action-oriented format following the pattern of other agent prompts in .github/aw/.

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.